MatchAlias

MatchAlias
Header:	Aliases.h		Carbon status:	Supported

Identifies a list of possible matches and passes the list through an optional selection filter. The filter can return more than one possible match.

OSErr MatchAlias (
    ConstFSSpecPtr fromFile, 
    UInt32 rulesMask, 
    AliasHandle alias, 
    SInt16 *aliasCount, 
    FSSpecArrayPtr aliasList, 
    Boolean *needsUpdate, 
    AliasFilterUPP aliasFilter, 
    void *yourDataPtr
);

fromFile: A pointer to the starting point for a relative search. If you do not want MatchAlias to perform a relative search, set fromFile to NULL. If you want MatchAlias to perform a relative search, pass a pointer to a file system specification record that describes the starting point for the search.
rulesMask: A set of rules to guide the resolution. Pass the sum of all of the rules you want to invoke. For a description of the value syou can use in this parameter, see Matching Constants”.
alias: A handle to the alias record to be resolved.
aliasCount: On input, a pointer to the maximum number of possible matches to return. On output, the actual number of matches returned.
aliasList: A pointer to the array that holds the results of the search, a list of possible candidates.
needsUpdate: A pointer to a Boolean flag that indicates whether the alias record to be resolved needs to be updated.
aliasFilter: An application-defined filter function. The Alias Manager executes this function each time it identifies a possible match and after the search has continued for three seconds without a match. Your filter function returns a Boolean value that determines whether the possible match is discarded (true) or added to the list of possible targets (false). It can also terminate the search by setting the variable parameter quitFlag. See AliasFilterProcPtr for a description of the filter function.
yourDataPtr: A pointer to data to be passed to the filter function. The yourDataPtr parameter can point to any data that your application might need in the filter function.

function result: A result code.

DISCUSSION

If MatchAlias finds the parent directory on the correct volume but does not find the target, it sets the aliasCount parameter to 1, puts the file system specification record for the target in the results list, and returns fnfErr. The FSSpec record is valid, although the object it describes does not exist. This information is intended as a “hint” that lets you explore possible solutions to the resolution failure. You can, for example, use the FSSpec record and the File Manager function FSpCreate to create a replacement for a missing file.

After it identifies a target, MatchAlias compares some key information about the target with the same information in the record. If the information does not match, MatchAlias sets the needsUpdate flag to true. The key information is

the name of the target
the directory ID of the target’s parent
the file ID or directory ID of the target
the name and creation date of the volume on which the target resides

The MatchAlias function also sets the needsUpdate flag to true if it identifies a list of possible matches rather than a single match or if kARMsearchRelFirst is set but the target is identified through either an absolute search or an exhaustive search. Otherwise, the MatchAlias function sets the needsUpdate flag to false. MatchAlias always sets the needsUpdate flag to false when resolving an alias created by NewAliasMinimal. If you want to update the alias record to reflect the final results of the resolution, call UpdateAlias.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.